docs: design study for #83 — delegation and key mapping - #87
Merged
Conversation
Discussion #86 captured this, but a discussion is easy to lose and hard to cite from code review. misc/docs/ is where dol's durable design records live, so this lands next to dol_issue18_design.md (its inverse) and dol_issue10_design.md. Records, with the running-code evidence for each: - TWO delegation routes, not one -- Store.__getattr__ AND DelegatedAttribute.__get__. A fix covering one is a silent no-op on the other, which is why several past fixes had to be applied twice. - The 13-package census, stated accurately: the defect is overwhelmingly LATENT (it bites only when a user applies a key codec), and 12 survey claims were refuted outright. An earlier downstream draft claimed the family was actively destroying data; it is not, and the record says so. - Options A-F with what each actually costs: A wrapped_self -- has its own silent hole: degrades to the raw leaf when nothing holds a strong reference to the wrapper, and where the leaf owns a prefix the wrong answer is a plausible str. CPython 3.10-3.14. Detectable via the KeysView probe, so it can be made loud. B declarative -- dol already ships this (ingoing_key_methods), untested and broken for leaf-defined methods. The reflective test is the part that holds, not the registry. C free funcs -- break on a non-Store layer, where the method form is right. dol's own instance (content_url) had the bug until #85. D rebind -- rejected in dol_issue18_design.md with evidence; binds to the INNERMOST wrap, so it misses the Pipe case it exists to fix. E parallel maps -- broken as an ATTRIBUTE (a wrapper does not re-wrap one), correct by construction as a sibling STORE keyed through __getitem__. The only option needing no resolution primitive. F is-a -- the terminal fix; dissolves #83, #18 and #6 together. Section 5 is the explicit carry-forward list for a future redesign: the has-a/is-a choice is one decision not three; a wrapper must be able to express "this method takes a key"; the two routes must be unified; key mapping needs an inverse (inward->outward has no supported helper); weakref backrefs are the wrong substrate for correctness; non-Store layers exist in the wild; and "how many keyed methods does this force adapters to write?" is a design metric worth tracking (azuredol has ~0 and is clean). Indexed from CLAUDE.md and dol_misc_docs_guide.md. All file:line citations verified against the current source.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Docs only. Makes the #83 investigation durable and citable, next to
dol_issue18_design.md(its inverse) anddol_issue10_design.md.Discussion #86 already captured this, but a discussion is easy to lose and awkward to cite from
a code review;
misc/docs/is where dol's design records live.What it records
Store.__getattr__andDelegatedAttribute.__get__. Afix covering one is a silent no-op on the other, which is why several past fixes had to be
applied twice.
bites only when a user applies a key codec — and 12 survey claims were refuted outright.
An earlier downstream draft claimed the family was actively destroying data; it is not, and the
record now says so explicitly.
right and are not:
wrapped_selfhas its own silent hole (degrades to the raw leaf when nothing holds a strongreference to the wrapper; the wrong answer is a plausible
strwhere the leaf owns aprefix). Reproduced on CPython 3.10–3.14. Detectable, so it can at least be made loud.
Storelayer — where the method form is right.dol's own instance (
content_url) had the bug until fix: two delegation bugs in dol's own code (content_url, filesys key validation) #85.as a sibling store; those are different designs and get conflated.
the has-a/is-a choice is one decision rather than three symptoms; a wrapper must be able to
express "this method takes a key"; the two routes must be unified; key mapping needs an inverse
(inward→outward has no supported helper, so every adapter hand-rolls it); weakref backrefs are
the wrong substrate for correctness; non-
Storelayers exist in the wild (dol ships a recipefor one); and "how many keyed methods does this force adapters to write?" is a design metric
worth tracking —
azuredolhas ~0 and is the clean one.Indexed from
CLAUDE.mdandmisc/docs/dol_misc_docs_guide.md. Everyfile:linecitationverified against current source. Suite unchanged: 525 passed, 3 skipped.